EnableBinaryPayloads

Boolean

false

Purpose

Set the value of the EnableBinaryPayloads parameter to true if you want to send or receive binary‑formatted data (for example, an image or audio file). This enables the:

• Generation of Direct REST responses with binary‑formatted payloads.

• Direct REST methods to ingest binary‑formatted payloads.

Generating REST Responses with Binary Payloads

To generate REST responses with Binary payloads:

1. Set the value of the EnableBinaryPayloads parameter to true.

2. Create a REST method that returns a Binary primitive return type.

3. Use the JadeRestService class addResponseHeaderField method to set the "Content‑Type" header field of the response to identify the format of the binary data; for example, "image/png".

The following is an example of such a REST method.

getImage(): Binary updating;
vars
    file : File;
begin
    addResponseHeaderField("Content-Type", "image/png");
    create file transient;
    file.kind := file.Kind_Binary;
    file.mode := file.Mode_Input;
    file.fileName := "<path to png image file>";
    return file.readBinary(file.fileLength());
epilog
    delete file;
end;

This method would generate a REST response of the following form.

HTTP/1.1 200 OK
Connection: close
Content-Length: 831153
Content-Type: image/png

PNG

  T   Bq "bIʞ    `FNs
b5[ $  G ď[6 ۪: P(
...

If a method generates a response with a binary payload, the JadeRestService class replyBinary extension method is called rather than the reply method.

You can reimplement the method to allow the application specific post‑processing of the response, but you must call the JadeRestService class implementation to complete the processing by making an inheritMethod call.

Ingesting REST Requests with Binary Payloads

To ingest REST requests with Binary payloads:

1. Set the value of the EnableBinaryPayloads parameter to true.

2. Create a REST method that has a Binary parameter.

3. Ensure that the request has a "Content‑Type" header that identifies the payload of the message is binary, as shown in the following example of a formatted REST request.

   POST /image HTTP/1.1
   Content-Type: image/png
   Content-Length: 831153
   ëPNG
   ␦
   IHDR3/╓ò╦sRGB«╬ΘgAMA▒Å
   ⁿa      pHYstt▐fx ÑIDATx^∞}ÿòe·╛0}·LR* 3L╥▌▌▌▌▌é╡vδ¬k╗vφÜ╗v¡▌
   "óÇÇá`Çä⌠╠£√▌╧√╛gå╤²²╖$ƒ√║>╧Ö▀  <τ╝≈w╟s␦
   àBíP(
   àΓ─ie/P(
   ....

The above formatted request could be ingested by a REST method like the following, which takes the payload and writes it to a file on disk (assuming that is both safe and something that you want to do with the binary payload).

postImage(image: Binary): String;
vars
    file : File;
begin
    create file transient;
    file.mode := File.Mode_Output;
    file.kind := File.Kind_Binary;
    file.fileName := "<path to file>";
    file.writeBinary(image);
epilog
    delete file;
end;

Parameter Scope

The EnableBinaryPayloads parameter affects all REST applications on the node. However, you can specify the setting in the format <application‑name>_EnableBinaryPayloads to affect only that REST application; for example, to send binary‑formatted data as a payload in Direct REST responses to a REST application called MyApp, specify the following.

MyApp_EnableBinaryPayloads=true

The EnableBinaryPayloads parameter affects all REST applications on the node. However, you can specify the setting in the format [<application‑name>]_EnableBinaryPayloads to affect only the specified REST application. For example, to send binary‑formatted data as a payload in Direct REST responses to a REST application called MyApp, specify the following.

MyApp_EnableBinaryPayloads=true

If you want only the application called RestServer to have a binary‑formatted payload in Direct REST responses and all payloads of all other REST applications on the same node to be encoded as UTF8 text, use the following Jade initialization file settings.

[WebOptions]
EnableBinaryPayloads=false
RestServer_EnableBinaryPayloads=true

For details about defining a REST service application, see "Defining a REST Service Application" and "Running a REST Service Application in the Direct REST Mode", in Chapter 11 of the Developer's Reference.

2022.0.05 and higher